Classification Status API

Retrieve classification status for a sample

GET /api/samples/v3/{hash_value}/classification/

Get classification results for a sample. The sample must be present on the appliance.

By default, if the requested sample is not found on the appliance, or if classification for the sample is “UNKNOWN”, the API automatically sends a request to Spectra Intelligence for any classification information and return it in the response. The prerequisite for this functionality is a properly configured Spectra Intelligence account on the appliance.

To disable automatic Spectra Intelligence querying, the optional parameter localonly can be used in the request. When set to localonly=1, it specifies that only local classification data should be returned for the sample, without falling back to querying Spectra Intelligence.

Queries from the appliance to Spectra Intelligence are limited to 10 000 requests per day. If the user makes 10 000 requests to Spectra Intelligence via this endpoint (by querying hashes that don’t exist on the appliance), the endpoint will respond with a 429 HTTP status code until the start of the next calendar day (00:01 UTC).

important

Spectra Intelligence queries for samples that exist on the appliance, but don’t have a local classification (samples with Unknown status) do not count towards the daily limit. Spectra Intelligence queries for samples that don’t exist on the appliance are the only ones that count towards the limit.

Request Format

Request Parameters

NAME	REQUIRED	DESCRIPTION	TYPE
hash_value	Required	Hash of the sample for which the classification status should be returned. Only one hash can be submitted in one request. Supported hash types: SHA1, SHA256, SHA512, MD5	path, string
localonly	Optional	Defines the source of the classification data to be returned. Supported values: 0, 1. If it is set to 1, automatic requests to Spectra Intelligence are disabled, and av_scanners=1 cannot be used in the same request. If the parameter is omitted from the request, or submitted with the value of 0 (default), the API returns classification status for samples on the Spectra Analyze appliance. If the requested samples are not found on the appliance, it automatically sends a request to Spectra Intelligence. If the parameter is submitted with the value of 1, the API returns classification status only for samples on the appliance and does not send requests to Spectra Intelligence.	query, string
av_scanners	Optional	Specifies whether to include the AV scanners summary information in the response. Supported values: 0, 1. If the parameter is omitted from the request, or submitted with the default value of 0, the AV scanners metadata is not included in the response. When set to 1, AV scanners metadata is included in the response. The API first looks for any existing local metadata. If there is no local metadata, a request is sent to Spectra Intelligence. This request counts towards the Spectra Intelligence usage quota. This parameter cannot be used with localonly=1 in the same request, because that disables requests to Spectra Intelligence.	query, string

Request Examples

cURL

# Add --insecure before the URL if you are using a self-signed SSL certificate
curl -X GET 'https://appliance.example.com/api/samples/v3/cf8e42c4a0862c807f0de3c656d2cd1c99cc5a27/classification/' \
  --header 'Authorization: Token exampletoken'

Python

import requests

# Change the values of token and hash_value
token = "exampletoken"
hash_value = "examplehash"
# Change the host name in the URL and the fields to be included in the response
url = f"https://appliance.example.com/api/v2/samples/{hash_value}/classification/"

headers = {
    "Authorization": f"Token {token}"
}

# Add verify=False in the request if you are using a self-signed SSL certificate
response = requests.get(url, headers=headers)
print(response.text)

Python with optional parameters

import requests

# Change the values of token and hash_value
token = "exampletoken"
hash_value = "examplehash"
# Change the host name in the URL and the fields to be included in the response
url = f"https://a1000.example.com/api/v2/samples/{hash_value}/classification/?av_scanners=1"

headers = {
    "Authorization": f"Token {token}"
}

# Add verify=False in the request if you are using a self-signed SSL certificate
response = requests.get(url, headers=headers)
print(response.text)

Response Format

Response Examples

Default response

{
  "classification": "malicious",
  "riskscore": 10,
  "first_seen": "2014-08-27T04:35:43Z",
  "last_seen": "2016-04-30T04:11:00Z",
  "classification_result": "Win32.Backdoor.Poison",
  "classification_origin": { <hashes> },
  "classification_reason: "CLOUD"
}

Response when the requested sample is not found on the appliance

{
   "message": "Hash not found.",
   "hash_value": "3d879d037184b17e47bc3391ff6c0b72"
}

Response Fields

FIELD NAME	TYPE	DESCRIPTION
sha1	string	SHA1 hash of the sample
sha256	string	SHA256 hash of the sample
md5	string	MD5 hash of the sample
classification	string	Indicator of sample status (MALICIOUS, SUSPICIOUS, GOODWARE, UNKNOWN)
riskscore	integer	Risk score value of the sample (0-10, lowest to highest)
first_seen	string	UTC date-time (example: “2014-08-27T04:35:43Z”)
last_seen	string	UTC date-time (example: “2014-08-27T04:35:43Z”)
classification_result	string	RL normalized threat name (example: “Win32.Backdoor.Poison”)
classification_origin	object	List of hashes that the sample classification came from. Returns null if the request has been made directly to Spectra Intelligence, or if Spectra Intelligence has not been queried for local samples.
classification_reason	string	Indicates the reason for the sample’s classification. Can be one of the following: UNKNOWN, ANTIVIRUS, SIGNATURE, CERTIFICATE, FORMAT, EXPLOIT, YARA, RHA1, USER, CLOUD
cloud_last_lookup	string	Timestamp when the last response from Spectra Intelligence was received (if the sample resides on the appliance). Returns null if the request has been made directly to Spectra Intelligence, or if Spectra Intelligence has not been queried for local samples.
data_source	string	Indicates the source of the provided data set - either the appliance or Spectra Intelligence.
av_scanners	object	Returned only if the av_scanners=1 parameter is included in the request. Provides information about AV scanner count, matches, and percentage for the requested sample. Corresponds to the av_scanners_summary object from the Sample Details API response.

Response Status Codes

CODE	DESCRIPTION
200	OK. This response is returned even when the sample is not found on the appliance.
403	Forbidden. This response is returned when the request isn’t authenticated.
404	Invalid or malformed hash.
429	Too many requests (daily Spectra Intelligence query max limit reached).
503	Service unavailable (Spectra Intelligence API-related errors, i.e., Unauthorized).